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

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

Status

Draft

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提取
  • 创建租户认证中间件
• 验证租户管理功能 (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，与认证模块的认证中间件是独立的两套系统。

采用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并提取租户ID
    const decoded = jwt.verify(token, process.env.JWT_SECRET!) as any;
    const tenantId = decoded.tenantId;

    if (!tenantId) {
      return c.json({ message: 'Tenant ID not found in token' }, 401);
    }

    // 设置租户上下文
    c.set('tenantId', tenantId);
    await next();
  } catch (error) {
    console.error('Tenant auth middleware error:', error);
    return c.json({ message: 'Invalid token or tenant context' }, 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

{{agent_model_name_version}}

Debug Log References

Completion Notes List

File List

QA Results

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