mini-starter/docs/stories/007.001.tenant-base-package-creation.md

Story 007.001: 租户基础包创建和租户管理

Status

Ready for Review

Story

As a 系统管理员 I want 创建租户基础包和租户管理功能 so that 能够为多租户系统提供基础的租户管理和上下文支持

Acceptance Criteria

1. 成功复制 @d8d/merchant-module 为 @d8d/tenant-module-mt 租户管理模块
2. 修改商户实体为租户实体，调整字段和业务逻辑
3. 实现租户管理API，包括租户的CRUD操作
4. 创建租户上下文管理机制
5. 验证租户管理功能正常工作
6. 确保现有单租户系统功能完全不受影响

Tasks / Subtasks

• 复制 @d8d/merchant-module 为 @d8d/tenant-module-mt (AC: 1)
  • 创建新的包目录结构
  • 复制并修改package.json配置
  • 更新包名和描述信息
• 修改商户实体为租户实体 (AC: 2)
  • 重命名Merchant实体为TenantEntityMt
  • 调整字段映射（商户名称→租户名称，用户名→租户代码等）
  • 移除商户特定字段（登录统计、密码等）
  • 添加租户特定字段（状态、配置等）
• 实现租户管理API (AC: 3)
  • 创建租户服务层，基于现有商户服务修改
  • 实现统一的租户CRUD路由（无需区分管理员和用户角色）
  • 更新Schema定义
  • 添加租户类型定义
• 创建租户认证中间件 (AC: 4)
  • 实现tenantAuthMiddleware函数
  • 添加JWT验证和租户ID提取
  • 简化路由结构，删除不必要的用户/管理员路由区分
  • 添加简单的登录接口，使用固定账号密码生成JWT token
• 验证租户管理功能 (AC: 5)
  • 编写API集成测试
  • 验证租户数据隔离
  • 验证现有单租户系统功能完整性 (AC: 6)

Dev Notes

相关源树信息

packages/
├── merchant-module/ (源包)
│   ├── src/
│   │   ├── entities/merchant.entity.ts
│   │   ├── services/merchant.service.ts
│   │   ├── routes/
│   │   ├── schemas/
│   │   └── types/
│   └── package.json
└── tenant-module-mt/ (目标包)
    ├── src/
    │   ├── entities/tenant.entity.ts
    │   ├── services/tenant.service.ts
    │   ├── routes/
    │   ├── schemas/
    │   └── types/
    └── package.json

技术上下文

• 现有系统: TypeScript + Node.js + TypeORM + Hono
• 数据库: PostgreSQL
• 包管理: pnpm workspace
• 架构模式: 模块化架构，CRUD操作，认证中间件

实体映射关系

从商户实体到租户实体的字段映射：

• name (商户名称) → name (租户名称)
• username (用户名) → code (租户代码，唯一标识)
• 移除：password, loginNum, loginTime, loginIp, lastLoginTime, lastLoginIp
• 添加：status (租户状态), config (租户配置)

租户认证中间件设计

重要说明：此租户认证中间件仅用于租户管理API，与认证模块的认证中间件是独立的两套系统。

设计变更：租户管理不需要区分管理员和用户角色，使用固定的超级管理员账号进行管理，通过JWT token进行认证。

认证逻辑：验证JWT token并检查是否为超级管理员权限（固定的超级管理员ID为1），而不是提取租户ID。

新增功能：提供简单的登录接口，使用固定的账号和密码生成JWT token，方便测试和管理。

采用Hono中间件模式与现有技术栈统一：

import { Context, Next } from 'hono';

export async function tenantAuthMiddleware(c: Context, next: Next) {
  try {
    const authHeader = c.req.header('Authorization');
    if (!authHeader) {
      return c.json({ message: 'Authorization header missing' }, 401);
    }

    const tokenParts = authHeader.split(' ');
    if (tokenParts.length !== 2 || tokenParts[0] !== 'Bearer') {
      return c.json({ message: 'Authorization header missing' }, 401);
    }

    const token = tokenParts[1];
    if (!token) {
      return c.json({ message: 'Token missing' }, 401);
    }

    // 验证JWT并检查是否为超级管理员
    const decoded = jwt.verify(token, process.env.JWT_SECRET!) as any;
    const isSuperAdmin = decoded.isSuperAdmin;

    if (!isSuperAdmin) {
      return c.json({ message: 'Access denied. Super admin privileges required' }, 403);
    }

    await next();
  } catch (error) {
    console.error('Tenant auth middleware error:', error);
    return c.json({ message: 'Invalid token or authentication failed' }, 401);
  }
}

依赖关系

• 共享包依赖：@d8d/shared-crud, @d8d/shared-types, @d8d/shared-utils
• 不依赖其他业务包，避免循环依赖
• 保持与单租户系统相同的技术栈和架构模式

测试

测试标准

• 测试文件位置: tests/ 目录下
• 测试框架: Vitest
• 测试模式: API集成测试
• 测试覆盖: 租户管理API接口

具体测试要求

• 租户CRUD操作API测试
• 租户上下文管理集成测试
• 租户数据隔离验证
• 现有单租户系统回归测试

Change Log

Date	Version	Description	Author
2025-11-13	1.0	初始故事创建	Claude

Dev Agent Record

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

Agent Model Used

Claude Code

Completion Notes List

• ✅ 成功复制 @d8d/merchant-module 为 @d8d/tenant-module-mt 租户管理模块
• ✅ 修改商户实体为租户实体，调整字段和业务逻辑
• ✅ 实现租户管理API，包括租户的CRUD操作
• ✅ 创建租户认证中间件（使用固定的超级管理员ID为1进行认证）
• ✅ 添加简单的登录接口，使用固定账号密码生成JWT token
• ✅ 验证租户管理功能正常工作（所有集成测试通过）
• ✅ 确保现有单租户系统功能完全不受影响

设计变更

• 简化认证模型：租户管理不需要区分管理员和用户角色，使用固定的超级管理员账号（ID为1）进行管理
• 统一路由结构：删除不必要的用户/管理员路由区分，只保留一套统一的租户管理路由
• 使用共享JWT工具：租户认证中间件使用共享的JWTUtil进行token验证
• 新增登录接口：提供简单的登录接口，使用固定账号密码（superadmin/admin123）生成JWT token

File List

• /packages/tenant-module-mt/package.json - 包配置
• /packages/tenant-module-mt/src/entities/tenant.entity.ts - 租户实体
• /packages/tenant-module-mt/src/services/tenant.service.ts - 租户服务
• /packages/tenant-module-mt/src/schemas/tenant.schema.ts - 租户Schema
• /packages/tenant-module-mt/src/middleware/tenant-auth.middleware.ts - 租户认证中间件
• /packages/tenant-module-mt/src/routes/index.ts - 统一租户路由
• /packages/tenant-module-mt/src/routes/auth.routes.ts - 认证路由
• /packages/tenant-module-mt/tests/integration/tenant-routes.integration.test.ts - 租户管理集成测试
• /packages/tenant-module-mt/tests/integration/auth-routes.integration.test.ts - 认证接口集成测试

QA Results

此部分将由QA代理在QA审查后填写