# 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中间件模式与现有技术栈统一：
```typescript
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审查后填写*